.\"
.\" SQL NAME TRANSFORMATIONS
.\"
.SH SQL NAME TRANSFORMATIONS
The ODB compiler provides a number of mechanisms for transforming
automatically-derived SQL names, such as tables, columns, etc.,
to match a specific naming convention. At the higher level, we can
add a prefix to global names (tables and, for some databases,
indexes and/or foreign keys) with the
.B --table-prefix
option. Similarly, we can specify custom suffixes for automatically-derived
index
.RB ( --index-suffix ;
default is
.BR _i ),
foreign key
.RB ( --fkey-suffix ;
default is
.BR _fk ),
and sequence
.RB ( --sequence-suffix ;
default is
.BR _seq )
names. Finally, we can also convert all the names to upper or lower
case with the
.B --sql-name-case
option (valid values are
.B upper
and
.BR lower ).

At the lower level we can specify a set of regular expressions to
implement arbitrary transformations of the automatically-derived SQL
names. If we want a particular regular expression only to apply to
a specific name, for example, table or column, then we use one of the
.B --\fIkind\fB-regex
options, where
.I kind
can be
.BR table ,
.BR column ,
.BR index ,
.BR fkey ,
.BR sequence ,
or
.BR statement .
On the other hand, if we want our regular expressions to apply to all SQL
names, then we use the
.B --sql-name-regex
option.

The interaction between the higher and lower level transformations
is as follows. Prefixes and suffixes are added first. Then the
regular expression transformations are applied. Finally, if requested,
the name is converted to upper or lower case. Note also that all of
these transformations except for
.B --table-prefix
only apply to automatically-derived names. In other words, if a table,
column, etc., name was explicitly specified with a pragma, then it
is used as is, without applying any (except for the table prefix)
transformations.

The value for the
.B --*-regex
options is a Perl-like regular expression in the form
.BI / pattern / replacement /\fR.
Any character can be used as a delimiter instead of
.B /
and the delimiter can be escaped inside
.I pattern
and
.I replacement
with a backslash
.RB ( \e ).
You can also specify multiple regular expressions by repeating these
options.

All the regular expressions are tried in the order specified with the
name-specific expressions (for example,
.BR --table-regex)
tried first followed by the generic expressions
.RB ( --sql-name-regex ).
The first expression that matches is used.

As an example, consider a regular expression that transforms a class
name in the form
.B CFoo
to a table name in the form
.BR FOO:

.B --table-regex '/C(.+)/\eU$1/'

As a more interesting example, consider the transformation of class
names that follow the upper camel case convention (for example,
.BR FooBar )
to table names that follow the underscore-separated, all upper case
convention (for example,
.BR FOO_BAR ).
For this case we have to use separate expressions to handle one-word,
two-word, etc., names:

.B --table-regex '/([A-z][a-z]+)/\eU$1/'

.B --table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\eU$1_$2/'

See also the REGEX AND SHELL QUOTING section below.
.\"
.\" REGEX AND SHELL QUOTING
.\"
.SH REGEX AND SHELL QUOTING
When entering a regular expression argument in the shell command line
it is often necessary to use quoting (enclosing the argument in " "
or ' ') in order to prevent the shell from interpreting certain
characters, for example, spaces as argument separators and $ as
variable expansions.

Unfortunately it is hard to achieve this in a manner that is portable
across POSIX shells, such as those found on GNU/Linux and UNIX, and
Windows shell. For example, if you use " " for quoting you will get
a wrong result with POSIX shells if your expression contains $. The
standard way of dealing with this on POSIX systems is to use ' '
instead. Unfortunately, Windows shell does not remove ' '  from
arguments when they are passed to applications. As a result you may
have to use ' ' for POSIX and " " for Windows ($ is not treated as
a special character on Windows).

Alternatively, you can save regular expression options into a file,
one option per line, and use this file with the
.B --options-file
option. With this approach you don't need to worry about shell quoting.
.\"
.\" DIAGNOSTICS
.\"
.SH DIAGNOSTICS
If the input file is not valid C++,
.B odb
will issue diagnostic messages to STDERR and exit with non-zero exit code.
.\"
.\" BUGS
.\"
.SH BUGS
Send bug reports to the odb-users@codesynthesis.com mailing list.
.\"
.\" COPYRIGHT
.\"
.SH COPYRIGHT
Copyright (c) $copyright$.

Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
version 1.2; with no Invariant Sections, no Front-Cover Texts and
no Back-Cover Texts. Copy of the license can be obtained from
http://www.codesynthesis.com/licenses/fdl-1.3.txt
